home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 3 / Cream of the Crop 3.iso / c_lang / strpp31.zip / STR.DOC < prev    next >
Text File  |  1994-04-18  |  43KB  |  1,391 lines
  1.  
  2.                            String++ Version 3.10
  3.  
  4.                       Copyright 1994 by Carl Moreland
  5.                                  04/13/94
  6.  
  7. ---------------------------------------------------------------------------
  8.  
  9.     String++ is a string class written for Borland/Turbo C++. It contains a
  10. variety  of  string processing functions such as Insert,  Delete,  Replace,
  11. Find,  Justify, and Trim, as well as  overloaded operators for  assignment,
  12. concatenation, and comparison.  For AWK programmers, there are standard AWK
  13. functions  such  as sub, substr, index, and split, as well as  support  for
  14. regular expressions in many functions.
  15.  
  16.     Some  of  the ways that strings may be declared or initialized  are  as
  17. follows:
  18.  
  19.     String    str;            // NULL string
  20.         str('H');        // single character
  21.         str("Hello World");    // char*
  22.         str(c, 5);        // make 5 copies of character c
  23.         str(p, 5);        // char* p, begin at p[5]
  24.         str(p, 5, 3);        // begin at p[5], use 3 chars
  25.         str(s);            // another String
  26.         str(s, 5);        // String s, begin at s[5]
  27.         str(s, 5, 3);        // begin at s[5], use 3 chars
  28.         str(45);        // convert an int to a string
  29.         str(1.23);        // convert a float to a string
  30.         str(1.23, "%6.2f");    // convert a float to a string
  31.                     //   using a format specifier
  32.         str = 'H';        // single character
  33.         str = "Hello World";    // char*
  34.                 str = 1.6e-19;        // any number
  35.         str = p;        // char* p
  36.         str = s;        // another string
  37.         str = x;        // any number
  38.  
  39. The following operators are available:
  40.  
  41.     =    assignment - see above
  42.     ()    str() returns the char* of the string
  43.     char    cast operator, returns the first char of the string
  44.     char*    cast operator, returns the char* of the string
  45.     *    *str returns str[0]
  46.     []    str[i] returns the ith character of str; [] can also assign
  47.         the ith character of a string.
  48.     +  +=    concatenates
  49.     <<    concatenates
  50.     *  *=    multiple duplicates
  51.     == !=    comparisons
  52.     <  >    comparisons
  53.     <= >=    comparisons
  54.  
  55. Some binary operators are declared as friend functions. This allows them to
  56. accept char, char*, and String as valid arguments on either side of the op-
  57. erator. Therefore, each of these statements is valid:
  58.  
  59.     s1 = "Hello" + s2;
  60.     s1 = s2 + "World";
  61.     s1 = "Hello" + s2 + "World";
  62.     if(s1 == "Hello World") ...
  63.     if("Hello World" == s1) ...
  64.  
  65. However,
  66.  
  67.     s1 = "Hello " + "World";
  68.  
  69. is not legal because a String object MUST appear on one side of the  opera-
  70. tor.  A more flexible way to assign the contents of a string is to use  the
  71. << operator:
  72.  
  73.     char c;
  74.     String s1, s2;
  75.     ...
  76.     int n = index(s1, c);
  77.  
  78.     s2 << "The location of " << c << " in " << s1 << " is " << n;
  79.  
  80. The << operator  is  overloaded to accept char, char*, String,  int,  long,
  81. float, and double.
  82.  
  83. The  following functions are supported.  See the reference section of  this
  84. document for function syntax and examples.
  85.  
  86.     Copy            Copy a string to a char*
  87.     Delete            Delete a substring
  88.     FindFirst        Find the first occurrence of a substring
  89.     FindLast        Find the last occurrence of a substring
  90.     FindNext        Find the next occurrence of a substring
  91.     FindPrev        Find the previous occurrence of a substring
  92.     gsub            Global substring substitution
  93.     Index, index        Position of a substring
  94.     Insert            Insert a substring
  95.     Justify            Justify the string
  96.     Left, left        Leftmost substring
  97.     Len            Length of the string
  98.     Length, length        Length of the string
  99.     match            Match a regular expression
  100.     Mid, mid        Middle substring
  101.     Minimize        Minimize the buffer space
  102.     ptr            Return the char* of a string
  103.     Replace            Replace a substring
  104.     Right            Rightmost substring
  105.     SetCaseSensitivity    Set case sensitivity for comparisons
  106.         SetCompare        Set the comparison function pointer
  107.     SetFloatFormat        Set the floating point format specifier
  108.     SetIncLength        Set the buffer increment length
  109.     SetMinLength        Set the buffer minimum length
  110.     SetSize            Set the buffer size
  111.     SetToLower        Set the toLower function pointer
  112.     SetToUpper        Set the toUpper function pointer
  113.     Split, split        Split a string on a field separator
  114.     Sub, sub        Leftmost substitution
  115.     SubStr, substr        Random substring
  116.     toLower, tolower    Case conversion
  117.     toUpper, toupper    Case conversion
  118.     Trim, trim        Remove outer whitespace
  119.     Value            Numeric value of a numeric string
  120.  
  121. String Buffers
  122. --------------
  123.  
  124.     The contents of a string is stored in a character array.  Although  the
  125. size of the array could be just large enough to hold the string,  the array
  126. would have to be reallocated if a single character is added to the  String.
  127. To improve speed,  this class utilizes a minimum string buffer size and  an
  128. incremental size.
  129.  
  130.     The minimum buffer size is the minimum amount of memory that is  initi-
  131. ally allocated for the character array.  The default size is 16 characters.
  132. Each  newly created string will automatically have a buffer size  equal  to
  133. this  minimum size, plus one extra byte for the NULL terminator. Therfore
  134.  
  135.     String s1;
  136.     String s2 = "Hello";
  137.  
  138. will  both have 17 bytes of memory allocated even though not all  17  bytes
  139. are used.  If the strings are appended to then the memory does not have  to
  140. be reallocated provided that the new length does not exceed 17 bytes:
  141.  
  142.     s1 = s2;
  143.     s2 += ", World";
  144.  
  145. The  minimum buffer length is stored in the private  variable  strMinLength
  146. You can set this to a new value with the SetMinLength() function:
  147.  
  148.     String::SetMinLength(24);
  149.  
  150. This  example sets the minimum buffer length to 24 bytes (plus 1)  for  all
  151. subsequently created strings. Note that the String class is used in calling
  152. this function even though any String instance could be used.
  153.  
  154.     A second variable is used in determining how a string buffer will grow.
  155. The  private  variable strIncLength specifies the minimum number  of  bytes
  156. that  is  added to the buffer when the string exceeds  the  current  buffer
  157. size.  The  default value is 8 bytes.  Whenever a string  needs  additional
  158. space,  it receives it in multiples of 8 bytes.  In the example  above,  s2
  159. contains "Hello, World". If we add some more:
  160.  
  161.     s2 += ", How are you?;
  162.  
  163. then  s2 will exceed 17 bytes and additional memory must be  allocated.  In
  164. this case,  s2 will need a total of 26 bytes (plus 1 for the NULL  termina-
  165. tor).  The original 17 bytes plus the incremental 8 bytes is not enough, so
  166. another incremental 8 bytes is added for a total of 33 bytes.  This  proce-
  167. dure also works for newly created strings that exceed strMinLength:
  168.  
  169.     String s3 = "This is a very long string.";
  170.  
  171. s3  requires 28 bytes, so again it will receive 33 bytes (17+8+8).  strInc-
  172. Length can be set using the SetIncLength() function:
  173.  
  174.     String::SetIncLength(16);
  175.  
  176.     The  reason for using minimum and incremental lengths is to reduce  the
  177. number  of memory allocations, which are time consuming.  The  drawback  is
  178. that each string will waste a small amount of memory;  for a moderate  size
  179. string  this  will  typically be strIncLength/2.  Making  strMinLength  and
  180. strIncLength larger will waste more memory but require fewer memory alloca-
  181. tions.  Setting them equal to 1 will waste no memory but each appendage op-
  182. eration will need to reallocate memory.  This is how older versions of this
  183. class worked (2.12 and prior).
  184.  
  185. Temporary Strings
  186. -----------------
  187.  
  188.     When using strings,  you should be aware that temporary string  objects
  189. are sometimes created and destroyed, and that they can degrade program per-
  190. formance. For example,
  191.  
  192.     s1 = s2 + "World";
  193.  
  194. creates a temporary string that is the combination of s2 and "World". It is
  195. this temporary string that is assigned to s1 via the = operator. The reason
  196. for  this is because the + operator is defined to accept two const  objects
  197. (in this case a String and a char*) and returns a newly created string. The
  198. = operator is defined to accept a String&, which in this case is the string
  199. that results from the + operation.  The compiler knows that this string  is
  200. temporary  and  will automatically delete it when the assignment to  s1  is
  201. done.
  202.  
  203.     Functions that accept String objects as arguments can also accept  char
  204. and char* objects, as well as other data types that are supported by String
  205. constructors. For example,  even though the index() function is defined  to
  206. accept two String arguments, this is legal:
  207.  
  208.     i = index(s1, "a");
  209.  
  210. The "a" argument  will be converted to a String object by the compiler  be-
  211. cause there is a String constructor that is defined for char*. Like the op-
  212. erator example above, this String object is temporary and is destroyed when
  213. the function returns.
  214.  
  215.     Based  on the above example,  is it necessary for the String  class  to
  216. overload  the various operators to accept data types that are already  sup-
  217. ported by constructors? The answer is no, but the overloaded operators will
  218. reduce  the number of temporary strings that are created and therefore  im-
  219. prove performance.  In the example above, if the + operator were  only  de-
  220. fined to accept two strings, then the "World" argument would cause the cre-
  221. ation  of a second temporary string.  Most of the string functions are  not
  222. overloaded  because they typically do not see the kind of repeated use  the
  223. operators get.  If there is a string function that will get heavy  repeated
  224. use  with non-string arguments (such as the index example above)  then  you
  225. might see some speed improvement by overloading the function.
  226.  
  227. Regular Expressions
  228. -------------------
  229.  
  230.     Regular expressions are text patterns that are used for  string  match-
  231. ing. Normally, strings are compared to other strings (or substrings) and we
  232. look for an absolute match. However, there are times when we want to test a
  233. string  in  a more general way.  For example, suppose we want to see  if  a 
  234. string contains any digits.  Using absolute string matching,  we would have
  235. to run 10 comparisons,  one for each digit.  Using regular expressions,  we
  236. can create a character class and make one comparison:
  237.  
  238.     String s1;
  239.     Regexp re = "[0-9]";
  240.  
  241.     if(s1 == re)
  242.       do_something();
  243.  
  244. In the above example, the regular expression contains "[0-9]". The brackets
  245. enclose  the character class 0-9 which matches any digit.  Therefore, if s1
  246. contains a digit then the comparison with re will be true.
  247.  
  248.     Before a regular expression can be used it must first be declared.  For
  249. example, this will not work:
  250.  
  251.     if(s1 == "[0-9]")
  252.       do_something();
  253.  
  254. because the == operator will compare s1 to the literal string "[0-9]". How-
  255. ever, this will work:
  256.  
  257.     if(s1 == Regexp("[0-9]"))
  258.       do_something();
  259.  
  260.     Several string functions include support for regular expressions.  Like
  261. the other AWK functions included with the String class,  the match function
  262. returns  the position of the matching substring using C's zero-based  array
  263. offset, and -1 if the match failed. Because the ~ operator is unary in C++,
  264. it could not be overloaded to provide the same functionality as in AWK. In-
  265. stead,  the == operator and the != operator have been overloaded to use re-
  266. gular expressions.
  267.  
  268.     For more information concerning the use of regular expressions, consult
  269. a text on Unix or the AWK language (such as _The AWK Programming Language_,
  270. by Aho, Kernighan, and Weinberger).
  271.  
  272. Using the String Class
  273. ----------------------
  274.  
  275.     Before using the String class, you need to set it up for the version of
  276. Borland C++ that you are using. In 3.x, Borland used a class named "String"
  277. in  the Container Class Library.  Therefore, you cannot have another  class
  278. named String.  In 4.x,  Borland used an entirely new class named  "string",
  279. so  another string class would be illegal.  In str.h there are two  typedef
  280. statements:
  281.  
  282.     typedef StrPP String
  283.     typedef StrPP string
  284.  
  285. These  basically define alternate names for the class StrPP,  which is  re-
  286. ferred  to throughout this document as "the String class". If you are using
  287. BC++ 3.x comment out the String typedef,  and if you are using 4.x  comment
  288. out the string typedef.  If you want to derive your own custom class  named
  289. string or String, comment out the appropriate typedef, or both.
  290.  
  291.     There  are  several ways to add the String class to your  program.  You
  292. could  simply copy all of the files to your project directory and  add  the
  293. cpp files to the project list, and #include "str.h" in any module that uses
  294. a string.  You could also compile the cpp files to object format and  place
  295. the  object  files  in  Borland's LIB directory and  the  header  files  in
  296. Borland's  H  directory.  Then add the obj files to the  project  list  and
  297. #include <str.h>.  Finally,  you could split the cpp files into  individual
  298. function  files and use them to create a more efficient lib file which  can
  299. be placed in Borland's LIB directory and added to the project list.  To use
  300. regular expressions you will also need to #include regexp.h in modules that
  301. use them.
  302.  
  303. ---------------------------------------------------------------------------
  304. ---------------------------------------------------------------------------
  305.  
  306. Class Operators:
  307.  
  308. ---------------------------------------------------------------------------
  309.  
  310. operator =
  311. ----------
  312.  
  313. Syntax:    String& operator=(char c);
  314.     String& operator=(char* p);
  315.     String& operator=(String& s);
  316.     String& operator=(int n);
  317.     String& operator=(unsigned int n);
  318.     String& operator=(long n);
  319.     String& operator=(unsigned long n);
  320.     String& operator=(float n);
  321.     String& operator=(double n);
  322.  
  323. Assigns contents to the string. In the case of float and double, the string
  324. format is determined by the format specifier fpFormat,  which is a  private
  325. member of the String class.  It may be set by either a previous constructor
  326. call or by an explicit call to SetFloatFormat().
  327.  
  328. ---------------------------------------------------------------------------
  329.  
  330. operator +
  331. ----------
  332.  
  333. Syntax:    String operator+(String& s1, char* s2);
  334.     String operator+(char* s1, String& s2);
  335.     String operator+(String& s1, String& s2);
  336.  
  337. Creates a new string by concatenating s2 to s1.
  338.  
  339. ---------------------------------------------------------------------------
  340.  
  341. operator +=
  342. -----------
  343.  
  344. Syntax:    String& operator+=(char c);
  345.     String& operator+=(char* p);
  346.     String& operator+=(String& s);
  347.  
  348. Concatenates the argument to the string.
  349.  
  350. ---------------------------------------------------------------------------
  351.  
  352. operator <<
  353. -----------
  354.  
  355. Syntax:    String& operator<<(char c);
  356.     String& operator<<(char* p);
  357.     String& operator<<(String& s);
  358.     String& operator<<(int n);
  359.     String& operator<<(unsigned int n);
  360.     String& operator<<(long n);
  361.     String& operator<<(unsigned long n);
  362.     String& operator<<(float n);
  363.     String& operator<<(double n);
  364.  
  365. Concatenates the argument to the string.  In the case of float and  double,
  366. the string format is determined by the format specifier fpFormat, which  is
  367. a  private member of the String class.  It may be set by either a  previous
  368. constructor call or by an explicit call to SetFloatFormat().
  369.  
  370. ---------------------------------------------------------------------------
  371.  
  372. operator *
  373. ----------
  374.  
  375. Syntax:    String operator*(String& s, int n);
  376.     String operator*(int n, String& s);
  377.  
  378. Creates a new string with 'n' duplications of String 's'.
  379.  
  380. ---------------------------------------------------------------------------
  381.  
  382. operator *=
  383. -----------
  384.  
  385. Syntax:    String& operator*=(int n);
  386.  
  387. Adds 'n'-1 duplications of the string to itself.
  388.  
  389. ---------------------------------------------------------------------------
  390.  
  391. operator ==
  392. operator !=
  393. operator <
  394. operator >
  395. operator <=
  396. operator >=
  397. -----------
  398.  
  399. Syntax:    int operator??(String& s1, String& s2);
  400.     int operator??(String& s1, char* s2);
  401.     int operator??(char* s1, String& s2);
  402.     int operator??(String& s1, char c);
  403.  
  404. Compares s1 to s2 and returns 1 if the operation is true,  0 otherwise.  In
  405. the special case of char c, the operator compares s1[0] to c.
  406.  
  407. ---------------------------------------------------------------------------
  408.  
  409. operator ()
  410. -----------
  411.  
  412. Syntax:    const char* operator()();
  413.     const char* operator()(int pos);
  414.     String      operator()(int pos, int len);
  415.  
  416. The  first  case returns the contents of the string (strPtr)  via  a  const
  417. char*. The second method returns strPtr+pos. The third method creates a new
  418. string using the substring beginning at position 'pos' with length 'len' of
  419. string *this.  The  first two methods are considered safe  ways  to  access
  420. strPtr  because  the const modifier protects strPtr from  modification.  In
  421. using  these methods to pass a char* representation of a string to a  func-
  422. tion, be aware that many functions expect a char*, not const char*. In this
  423. case, the safest thing to do is use the Copy() function.
  424.  
  425. ---------------------------------------------------------------------------
  426.  
  427. operator char
  428. operator char*
  429. --------------
  430.  
  431. Syntax:    operator const char();
  432.     operator const char*();
  433.  
  434. These are cast operators that are automatically called when a String object
  435. is  passed where a char or char* is expected.  The const modifier  prevents
  436. the contents of the String object from being unintentionally modified.
  437.  
  438. ---------------------------------------------------------------------------
  439.  
  440. operator *
  441. ----------
  442.  
  443. Syntax:    const char operator *();
  444.  
  445. Returns the first character in the string.
  446.  
  447. ---------------------------------------------------------------------------
  448.  
  449. operator []
  450. -----------
  451.  
  452. Syntax:    char& operator [](int i);
  453.  
  454. Returns the ith character in the string, or assigns the ith character.
  455.  
  456. ---------------------------------------------------------------------------
  457. ---------------------------------------------------------------------------
  458.  
  459. Class Functions:
  460.  
  461. ---------------------------------------------------------------------------
  462.  
  463. Copy
  464. ----
  465.  
  466. Syntax:    char* Copy(char *p);
  467.  
  468. Copies the  string  contents to a non-const character pointer.  Copy() will
  469. allocate  the memory for the pointer - it is up to you to free (delete) it.
  470. Normally,  the contents of a string are extracted with the  () operator  or
  471. the  char* cast operator.  However, these return a const char* that must be
  472. cast to a non-const char* for some C-style functions (most Borland  library
  473. functions will accept const char*).  Although you could also use the  ptr()
  474. method to return a non-const char*, this is considered unsafe as it comple-
  475. tely strips the inherent protection that the String class offers.
  476.  
  477. Example:
  478.  
  479.     char *ptr;
  480.     String s1 = "lowercase";
  481.  
  482.     strupr(s1());            // won't work - strupr() expects
  483.                     //   a non-const char*
  484.     strupr((char*)s1());        // cast to char* - this works
  485.     s1.Copy(ptr);            // copy s1 to char *ptr
  486.     strupr(ptr);            // normal C-style
  487.  
  488. See Also: ptr, operator char*, operator ()
  489.  
  490. ---------------------------------------------------------------------------
  491.  
  492. Delete
  493. ------
  494.  
  495. Syntax:    String& Delete(int pos, int len = 1);
  496.  
  497. Deletes a substring beginning at position 'pos' with length 'len'. If 'len'
  498. = 0, then the substring from 'pos' to the end of the string is deleted.
  499.  
  500. Example:
  501.  
  502.     String s1 = "This is a test";
  503.     s1.Delete(5, 3);        // s1 = "This a test"
  504.  
  505. See Also: gsub, Replace, sub, Sub, trim, Trim
  506.  
  507. ---------------------------------------------------------------------------
  508.  
  509. Find...
  510. -------
  511.  
  512. Syntax:    int FindFirst(String& s);
  513.     int FindNext(void);
  514.     int FindLast(String& s);
  515.     int FindPrev(void);
  516.  
  517. Finds the substring s in a string.  FindFirst() finds the first occurrence,
  518. and  FindNext()  finds subsequent occurrences.  FindLast() finds  the  last
  519. occurrence,  and FindPrev() finds preceding occurrences.  Note  that  Find-
  520. Next() and FindPrev() will continue to use the substring s from the initial
  521. call to FindFirst() or FindLast().
  522.  
  523. Example:
  524.  
  525.     String s1 = "This is a test";
  526.  
  527.     i = s1.FindFirst(" ");
  528.     while(i != -1)
  529.     {
  530.       s1.Delete(i, 1);
  531.       i = s1.FindNext();
  532.     }                // s1 = "Thisisatest"
  533.  
  534. See Also: index, Index, match
  535.  
  536. ---------------------------------------------------------------------------
  537.  
  538. Index
  539. -----
  540.  
  541. Syntax: int Index(String& t);
  542.     int index(Regexp& t);
  543.  
  544. Returns  the position of 't' in the string if it exists,  or -1 if it  does
  545. not. 't' can be a string or a regular expression.
  546.  
  547. Example:
  548.  
  549.     int i;
  550.     String s1 = "d:\\prog\\str";
  551.  
  552.     i = s1.Index(":");        // i = 1
  553.  
  554. See Also: FindFirst, FindNext, FindLast, FindPrev, index, match
  555.  
  556. ---------------------------------------------------------------------------
  557.  
  558. Insert
  559. ------
  560.  
  561. Syntax: String& Insert(int pos, String& s);
  562.  
  563. Inserts substring 's' at position 'pos'.
  564.  
  565. Example:
  566.  
  567.     String s1 = "This a test";
  568.  
  569.     s1.Insert(5, "is ");        // s1 = "This is a test"
  570.  
  571. See Also: Delete, gsub, justify, Justify, Replace, sub, Sub, trim, Trim
  572.  
  573. ---------------------------------------------------------------------------
  574.  
  575. Justify
  576. -------
  577.  
  578. Syntax: String& Justify(int type, int len,
  579.                         int mode = String::CLIP|String::TRIM);
  580.  
  581. Justifies the string by padding it with spaces until it is 'len' long.  The
  582. justification 'type' can be String::LEFT, String::CENTER, or String::RIGHT.
  583. If the string has any leading or trailing whitespaces (spaces or tabs) then
  584. they  are first removed if 'mode'|=String::TRIM.  If the string  is  longer
  585. than 'len' (after the optional removal of white spaces) then it is  clipped
  586. to len if 'mode'|=String::CLIP.
  587.  
  588. Example:
  589.  
  590.     String s1 = s2 = s3 = "Hello World";
  591.  
  592.     s1.Justify(String::LEFT, 20);      // s1 = "Hello World         "
  593.     s2.Justify(String::CENTER, 20);    // s2 = "    Hello World     "
  594.     s3.Justify(String::RIGHT, 20);    // s3 = "         Hello World"
  595.  
  596. See Also: Insert, justify, trim, Trim
  597.  
  598. ---------------------------------------------------------------------------
  599.  
  600. Left
  601. ----
  602.  
  603. Syntax: String& Left(int len);
  604.  
  605. Reduces the string to the leftmost 'len' characters.
  606.  
  607. Example:
  608.  
  609.     String s1 = s2 = s3 = "This is a test";
  610.  
  611.     s1.Left(4);            // s1 = "This"
  612.     s2.Mid(5, 4);            // s2 = "is a"
  613.     s3.Right(4);            // s3 = "test"
  614.  
  615. See Also: left, mid, Mid, right, Right, substr, SubStr
  616.  
  617. ---------------------------------------------------------------------------
  618.  
  619. Len, Length
  620. -----------
  621.  
  622. Syntax: int Len(void)    const;
  623.     int Length(void) const;
  624.  
  625. Returns the length of the string:
  626.  
  627. Example:
  628.  
  629.     int i;
  630.     String s1 = "Hello World";
  631.  
  632.     i = s1.Length();        // i = 11
  633.  
  634. See Also: length
  635.  
  636. ---------------------------------------------------------------------------
  637.  
  638. Mid
  639. ---
  640.  
  641. Syntax: String& Mid(int pos, int len);
  642.  
  643. Reduces the string to the substring beginning at position 'pos' with length
  644. 'len'.
  645.  
  646. Example:
  647.  
  648.     String s1 = s2 = s3 = "This is a test";
  649.  
  650.     s1.Left(4);            // s1 = "This"
  651.     s2.Mid(5, 4);            // s2 = "is a"
  652.     s3.Right(4);            // s3 = "test"
  653.  
  654. See Also: left, Left, mid, right, Right, substr, SubStr
  655.  
  656. ---------------------------------------------------------------------------
  657.  
  658. Minimize
  659. --------
  660.  
  661. Syntax:    void Minimize(void);
  662.  
  663. Minimizes the allocated buffer space for the string.  Normally, strings are
  664. allocated memory based on strMinLength and strIncLength,  which are the mi-
  665. nimum and incremental buffer lengths.  Therefore, a string could be alloca-
  666. ted more memory than it is using.
  667.  
  668. Example:
  669.  
  670.     String s1 = "Hello World";    // by default, s1 is allocated 17
  671.                     //   bytes of memory
  672.     s1.Minimize();            // now s1 uses 12 bytes
  673.  
  674. See Also: SetIncLength, SetMinLength, SetSize
  675.  
  676. ---------------------------------------------------------------------------
  677.  
  678. ptr
  679. ---
  680.  
  681. Syntax:    char* ptr(void);
  682.  
  683. Returns a non-const char* to the contents of the string. This is considered
  684. extremely  dangerous  because  it bypasses the protection  offered  by  the
  685. String class. However, there are some cases where a non-const char* must be
  686. used.  A  safer  mechanism for passing a non-const pointer is  to  use  the
  687. Copy() function to create a new char*.
  688.  
  689. Example:
  690.  
  691.     s1 = "lowercase";
  692.  
  693.     strupr(s1());        // won't work - strupr() expects char*
  694.     strupr(s1.ptr());    // this works
  695.  
  696. See Also: Copy, operator char*, operator()
  697.  
  698. ---------------------------------------------------------------------------
  699.  
  700. Replace
  701. -------
  702.  
  703. Syntax:    String& Replace(int pos, int len, String& to);
  704.     int     Replace(String& from, String& to, int count = 32767);
  705.     int     Replace(Regexp& from, String& to, int count = 32767);
  706.  
  707. The  first  case  replaces the substring beginning at  position  'pos'  and
  708. length  'len' with String 'to'.  The other cases replace  substring  'from'
  709. with  String 'to' up to 'count' times and returns the number  of  substitu-
  710. tions. 'from' can be a string or a regular expression.
  711.  
  712. Example:
  713.  
  714.     int i;
  715.     String s1 = "d:\\prog\\str";
  716.  
  717.     i = s1.Replace("\\", "/");    // i = 2
  718.                     // s1 = "d:/prog/str"
  719.  
  720. See Also: gsub, sub, Sub
  721.  
  722. ---------------------------------------------------------------------------
  723.  
  724. Right
  725. -----
  726.  
  727. Syntax: String& Right(int len);
  728.  
  729. Reduces the string to the rightmost 'len' characters.
  730.  
  731. Example:
  732.  
  733.     String s1 = s2 = s3 = "This is a test";
  734.  
  735.     s1.Left(4);            // s1 = "This"
  736.     s2.Mid(5, 4);            // s2 = "is a"
  737.     s3.Right(4);            // s3 = "test"
  738.  
  739. See Also: left, Left, mid, Mid, right, substr, SubStr
  740.  
  741. ---------------------------------------------------------------------------
  742.  
  743. SetCaseSensitivity
  744. ------------------
  745.  
  746. Syntax:    void SetCaseSensitivity(int cs);
  747.  
  748. Sets the case sensitivity when comparing strings.  An argument of 1 (or  no
  749. argument) will make comparisons case sensitive.  An argument of 0 will make
  750. comparisons case insensitive.
  751.  
  752. Example:
  753.  
  754.     String s1 = "Hello World";
  755.         String s2 = "HELLO WORLD";
  756.  
  757.     String::SetCaseSensitivity(0);    // turn off case sensitivity
  758.  
  759.         if(s1 == s2)...            // this will be true
  760.  
  761. See also: SetCompare
  762.  
  763. ---------------------------------------------------------------------------
  764.  
  765. SetCompare
  766. ----------
  767.  
  768. Syntax:    void SetCompare(int (*fp)(const char*, const char*));
  769.  
  770. The String class contains a static pointer to a function that performs  the
  771. string comparisons. SetCaseSensitivity(cs) will set the pointer to strcmp()
  772. (cs = 1) or to stricmp (cs = 0).  You can use SetCompare() to make it point
  773. to a custom comparison function. The function should have the form
  774.  
  775.     int my_strcmp(const char*, const char*)
  776.  
  777. Example:
  778.  
  779.     String s1 = "Hello World";
  780.         String s2 = "HELLO WORLD";
  781.  
  782.     String::SetCompare(my_strcmp);    // use a custom comparison function
  783.  
  784.         if(s1 == s2)...            // maybe it's true, maybe it's not
  785.  
  786. See also: SetCaseSensitivity
  787.  
  788. ---------------------------------------------------------------------------
  789.  
  790. SetFloatFormat
  791. --------------
  792.  
  793. Syntax:    void SetFloatFormat(char* format);
  794.  
  795. Sets  the floating point format specifier fpFormat which determines  how  a
  796. floating point number will be converted to a string.  The default specifier
  797. is "%10.4f". Note that the specifier is a static member of the String class
  798. and therefore it will affect all strings.  SetFloatFormat() is also  static
  799. and can be called with or without a String instance. Consult the standard C
  800. function printf() for information concerning floating point format specifi-
  801. ers.
  802.  
  803. Example:
  804.  
  805.     String s1 = 1.23;            // s1 = "    1.2300"
  806.     String::SetFloatFormat("%1.2f");    // set fpFormat to "%1.2f"
  807.     s1 = 1.23;                // s1 = "1.23"
  808.  
  809. ---------------------------------------------------------------------------
  810.  
  811. SetIncLength
  812. ------------
  813.  
  814. Syntax:    void SetIncLength(int len);
  815.  
  816. Sets the buffer increment size to 'len'. Strings are allocated memory based
  817. on  strMinLength and strIncLength,  which are the minimum  and  incremental
  818. buffer lengths.  A newly created string will have a minimum buffer size  of
  819. strMinLength+1,  and strings that are assigned or appended to will grow in-
  820. crementally by strIncLength.  The default values are strMinLength = 16  and
  821. strIncLength = 8. Note that both variables are static members of the String
  822. class  and therefore they will affect all strings.  SetIncLength() is  also
  823. static and can be called with or without a String instance.
  824.  
  825. Example:
  826.  
  827.     String s1 = "Hello World";    // s1 is initially allocated 17
  828.                     //   bytes of memory
  829.     s1 += ",how are you";        // buffer grows to 17+8 bytes
  830.     String::SetIncLength(16);    // now all Strings will grow
  831.                     //   incrementally by 16 bytes
  832.  
  833. See Also: Minimize, SetMinLength, SetSize
  834.  
  835. ---------------------------------------------------------------------------
  836.  
  837. SetMinLength
  838. ------------
  839.  
  840. Syntax:    void SetMinLength(int len);
  841.  
  842. Sets the minimum buffer size to 'len'.  Strings are allocated memory  based
  843. on  strMinLength and strIncLength,  which are the minimum  and  incremental
  844. buffer lengths.  A newly created string will have a minimum buffer size  of
  845. strMinLength+1,  and strings that are assigned or appended to will grow in-
  846. crementally by strIncLength.  The default values are strMinLength = 16  and
  847. strIncLength = 8. Note that both variables are static members of the String
  848. class  and therefore they will affect all strings.  SetMinLength() is  also
  849. static and can be called with or without a String instance.
  850.  
  851. Example:
  852.  
  853.     String s1 = "Hi";        // s1 is initially allocated 17
  854.                     //   bytes of memory
  855.     String::SetMinLength(8);    // now all Strings will begin with
  856.                     //   a minimum of 9 bytes
  857.  
  858. See Also: Minimize, SetIncLength, SetSize
  859.  
  860. ---------------------------------------------------------------------------
  861.  
  862. SetSize
  863. -------
  864.  
  865. Syntax:    int SetSize(int len);
  866.  
  867. Sets the string's buffer size to 'len'+1. If 'len' is less than the length
  868. of the string, then the buffer is simply minimized.
  869.  
  870. Example:
  871.  
  872.     String s1 = "Hi";        // s1 is initially allocated 17
  873.                     //   bytes of memory
  874.     s1.SetSize(8);            // now s1 uses 9 bytes of memory
  875.  
  876. See Also: Minimize, SetMinLength, SetIncLength
  877.  
  878. ---------------------------------------------------------------------------
  879.  
  880. SetToLower
  881. ----------
  882.  
  883. Syntax:    void SetToLower(int (*fp)(int));
  884.  
  885. The  String class  contains static pointers to the functions  that  perform
  886. case conversion.  You can use SetToLower() to make the strToLower  function
  887. pointer point to a custom tolower function.  The default is the  standard C
  888. library function tolower(). The function should have the form
  889.  
  890.     int my_tolower(int)
  891.  
  892. Example:
  893.  
  894.         String s1 = "HELLO WORLD";
  895.  
  896.     String::SetToLower(my_tolower);    // use a custom tolower function
  897.  
  898.         s1.toLower
  899.  
  900. See Also: SetToUpper, tolower, toLower, toupper, toUpper
  901.  
  902. ---------------------------------------------------------------------------
  903.  
  904. SetToUpper
  905. ----------
  906.  
  907. Syntax:    void SetToUpper(int (*fp)(int));
  908.  
  909. The  String class  contains static pointers to the functions  that  perform
  910. case conversion.  You can use SetToUpper() to make the strToUpper  function
  911. pointer point to a custom toupper function.  The default is the  standard C
  912. library function toupper(). The function should have the form
  913.  
  914.     int my_toupper(int)
  915.  
  916. Example:
  917.  
  918.         String s1 = "HELLO WORLD";
  919.  
  920.     String::SetToUpper(my_toupper);    // use a custom toupper function
  921.  
  922.         s1.toUpper
  923.  
  924. See Also: SetToLower, tolower, toLower, toupper, toUpper
  925.  
  926. ---------------------------------------------------------------------------
  927.  
  928. Split
  929. -----
  930.  
  931. Syntax: int Split(String*& a, String& fs);
  932.     int Split(String*& a, Regexp& fs);
  933.  
  934. Splits the string into String array 'a' on field separator 'fs'.  Array 'a'
  935. is  normally declared as an uninitialized pointer in the  calling  function
  936. and a reference to the pointer is passed to Split().  Split() will then al-
  937. locate  memory for the correct array size and return the number of  fields.
  938. 'fs' can be a string or a regular expression.  String *this remains unmodi-
  939. fied.
  940.  
  941. Example:
  942.  
  943.     int i;
  944.     String *array;
  945.     String s1 = "d:\\prog\\str";
  946.  
  947.     i = s1.Split(array, "\\");    // i = 3
  948.                     // array[0] = "d:"
  949.                     // array[1] = "prog"
  950.                     // array[2] = "str"
  951.  
  952. See Also: split
  953.  
  954. ---------------------------------------------------------------------------
  955.  
  956. Sub
  957. ---
  958.  
  959. Syntax: int Sub(String& from, String& to, int count = 32767);
  960.     int Sub(Regexp& from, String& to, int count = 32767);
  961.  
  962. Substitutes String 'to' for each substring that is matched by 'from', up to
  963. 'count'  times  and returns the number of substitutions.  'from' can  be  a
  964. string or a regular expression.
  965.  
  966. Example:
  967.  
  968.     int i;
  969.     String s1 = "d:\\prog\\str";
  970.  
  971.     i = s1.Sub("\\", "/");        // i = 2
  972.                     // s1 = "d:/prog/str"
  973.  
  974. See Also: gsub, Replace, sub
  975.  
  976. ---------------------------------------------------------------------------
  977.  
  978. SubStr
  979. ------
  980.  
  981. Syntax: String substr(int pos, int len = 32767);
  982.  
  983. Creates a new string that is the substring of String *this beginning at po-
  984. sition 'pos' with length 'len'. String *this remains unmodified.
  985.  
  986. Example:
  987.  
  988.     String s1 = "Don't just stand there...";
  989.     String s1a;
  990.  
  991.     s1a = s1.SubStr(11, 5);        // s1a = "stand"
  992.  
  993. See Also: left, Left, mid, Mid, right, Right, substr
  994.  
  995. ---------------------------------------------------------------------------
  996.  
  997. toLower
  998. -------
  999.  
  1000. Syntax: String& toLower(void);
  1001.  
  1002. Converts the string to lower case, and also returns the converted string.
  1003.  
  1004. Example:
  1005.  
  1006.     String s1 = "LOWERCASE";
  1007.  
  1008.     s1.toLower();            // s1 is now "lowercase"
  1009.  
  1010. See Also: SetToLower, SetToUpper, toLower, toupper, toUpper
  1011.  
  1012. ---------------------------------------------------------------------------
  1013.  
  1014. toUpper
  1015. -------
  1016.  
  1017. Syntax: String& toUpper(void);
  1018.  
  1019. Converts the string to upper case, and also returns the converted string.
  1020.  
  1021. Example:
  1022.  
  1023.     String s1 = "uppercase";
  1024.  
  1025.     s1.toUpper();            // s1 is now "UPPERCASE"
  1026.  
  1027. See Also: SetToLower, SetToUpper, tolower, toLower, toupper
  1028.  
  1029. ---------------------------------------------------------------------------
  1030.  
  1031. Trim
  1032. ----
  1033.  
  1034. Syntax: String& Trim(int mode = String::CENTER,
  1035.                       char ch = String::WHITESPACE);
  1036.  
  1037. Trims leading or trailing characters from a string.  The trimmed  character
  1038. defaults to String::WHITESPACE (spaces & tabs) and can be user-defined.
  1039.  
  1040. Example:
  1041.  
  1042.     String s1 = s2 = s3 = "    Spaces    ";
  1043.  
  1044.     s1.Trim(String::LEFT);         // s1 = "Spaces    "
  1045.     s2.Trim(String::RIGHT);        // s2 = "    Spaces"
  1046.     s3.Trim();            // s3 = "Spaces"
  1047.  
  1048. See Also: trim, Delete
  1049.  
  1050. ---------------------------------------------------------------------------
  1051.  
  1052. Value
  1053. -----
  1054.  
  1055. Syntax: int&           Value(int& n);
  1056.     unsigned int&  Value(unsigned int& n);
  1057.     long&          Value(long& n);
  1058.     unsigned long& Value(unsigned long& n);
  1059.     float&         Value(float& n);
  1060.     double&        Value(double& n);
  1061.  
  1062. Returns the value of a numeric string.
  1063.  
  1064. Example:
  1065.  
  1066.     int n1;
  1067.     String s1 = "12345";
  1068.  
  1069.     s1.Value(n1);            // n1 is now 12345
  1070.  
  1071. ---------------------------------------------------------------------------
  1072. ---------------------------------------------------------------------------
  1073.  
  1074. Awk-style Functions:
  1075.  
  1076. Note: AWK  begins array indexing at 1, whereas C/C++ begins array  indexing
  1077.       at 0.  Therefore, most of the implemented AWK functions return values
  1078.       that correspond to C-style indexing.  An AWK function that might nor-
  1079.       mally return a 0 as a failure indicator will return a -1 here.
  1080.  
  1081. ---------------------------------------------------------------------------
  1082.  
  1083. gsub
  1084. ----
  1085.  
  1086. Syntax: int gsub(String& from, String& to, String& s, int count = 32767);
  1087.     int gsub(Regexp& from, String& to, String& s, int count = 32767);
  1088.  
  1089. Substitutes  String 'to' for each substring in String s that is matched  by
  1090. 'from',  up to 'count' times.  Returns the number of  substitutions. 'from'
  1091. can be a string or a regular expression.
  1092.  
  1093. Example:
  1094.  
  1095.     int i;
  1096.     String s1 = "d:\\prog\\str";
  1097.  
  1098.     i = gsub("\\", "/", s1);    // i = 2
  1099.                     // s1 = "d:/prog/str"
  1100.  
  1101. See Also: Replace, sub, Sub
  1102.  
  1103. ---------------------------------------------------------------------------
  1104.  
  1105. index
  1106. -----
  1107.  
  1108. Syntax: int index(String& s, String& t);
  1109.     int index(String& s, Regexp& t);
  1110.  
  1111. Returns the position of 't' in String s if it exists, or -1 if it does not.
  1112. 't' can be a string or a regular expression.
  1113.  
  1114. Example:
  1115.  
  1116.     int i;
  1117.     String s1 = "d:\\prog\\str";
  1118.  
  1119.     i = index(s1, ":");        // i = 1
  1120.  
  1121. See Also: FindFirst, FindNext, FindLast, FindPrev, Index
  1122.  
  1123. ---------------------------------------------------------------------------
  1124.  
  1125. length
  1126. ------
  1127.  
  1128. Syntax: int length(String& s);
  1129.  
  1130. Returns the length of String s.
  1131.  
  1132. Example:
  1133.  
  1134.     int i;
  1135.     String s1 = "Hello World";
  1136.  
  1137.     i = length(s1);            // i = 11
  1138.  
  1139. See Also: Len, Length
  1140.  
  1141. ---------------------------------------------------------------------------
  1142.  
  1143. match
  1144. -----
  1145.  
  1146. Syntax: int match(String& s, Regexp re);
  1147.  
  1148. Returns the position of the leftmost longest substring of s matched by  the
  1149. regular  expression  re if it exists, or -1 if it does not.  Also sets  the
  1150. global variables RSTART and RLENGTH. RSTART is the starting position of the
  1151. matching substring and RLENGTH is the substring length.
  1152.  
  1153. Example:
  1154.  
  1155.     int i;
  1156.     String s1 = "banana";
  1157.     Regexp r1 = "a[a-z]*a"
  1158.  
  1159.     i = match(s1, r1);        // matched substring is "anana",
  1160.                     //   so i=1, RSTART=1, RLENGTH=5
  1161.  
  1162. See Also: index, Index, FindFirst, FindNext, FindLast, FindPrev
  1163.  
  1164. ---------------------------------------------------------------------------
  1165.  
  1166. split
  1167. -----
  1168.  
  1169. Syntax: int split(String& s, String*& a, String& fs);
  1170.     int split(String& s, String*& a, Regexp& fs);
  1171.  
  1172. Splits String 's' into String array 'a' on field separator 'fs'.  Array 'a'
  1173. is  normally declared as an uninitialized pointer in the  calling  function
  1174. and a reference to the pointer is passed to split().  split() will then al-
  1175. locate  memory for the correct array size and return the number of  fields.
  1176. 'fs' can be a string or a regular expression. String s remains unmodified.
  1177.  
  1178. Example:
  1179.  
  1180.     int i;
  1181.     String *array;
  1182.     String s1 = "d:\\prog\\str";
  1183.  
  1184.     i = split(s1, array, "\\");    // i = 3
  1185.                     // array[0] = "d:"
  1186.                     // array[1] = "prog"
  1187.                     // array[2] = "str"
  1188.  
  1189. See Also: Split
  1190.  
  1191. ---------------------------------------------------------------------------
  1192.  
  1193. sub
  1194. ---
  1195.  
  1196. Syntax: int sub(String& from, String& to, String& s);
  1197.     int sub(Regexp& from, String& to, String& s);
  1198.  
  1199. Substitutes  String 'to' for the leftmost substring of 's' that is  matched
  1200. by 'from'.  Returns the number of substitutions (0 or 1). 'from' can  be  a
  1201. string or a regular expression.
  1202.  
  1203. Example:
  1204.  
  1205.     int i;
  1206.     String s1 = "d:\\prog\\str";
  1207.  
  1208.     i = sub("\\", "/", s1);        // i = 1
  1209.                         // s1 = "d:/prog\str"
  1210.  
  1211. See Also: gsub, Replace, Sub
  1212.  
  1213. ---------------------------------------------------------------------------
  1214.  
  1215. substr
  1216. ------
  1217.  
  1218. Syntax: String substr(String& s, int pos, int len = 32767);
  1219.  
  1220. Creates  a new string that is the substring of String s beginning at  posi-
  1221. tion 'pos' with length 'len'. String s remains unmodified.
  1222.  
  1223. Example:
  1224.  
  1225.     String s1 = "Don't just stand there...";
  1226.     String s1a;
  1227.  
  1228.     s1a = substr(s1, 11, 5);    // s1a = "stand"
  1229.  
  1230. See Also: left, Left, mid, Mid, right, Right, SubStr
  1231.  
  1232. ---------------------------------------------------------------------------
  1233. ---------------------------------------------------------------------------
  1234.  
  1235. C-Style Functions:
  1236.  
  1237. ---------------------------------------------------------------------------
  1238.  
  1239. left
  1240. ----
  1241.  
  1242. Syntax: String left(char* p, int len);
  1243.  
  1244. Creates a new string that is the leftmost substring of p with length 'len'.
  1245. p remains unmodified.
  1246.  
  1247. Example:
  1248.  
  1249.     char* p1 = "This is a test";
  1250.     String s1a, s1b, s1c;
  1251.  
  1252.     s1a = left(p1, 4);        // s1a = "This"
  1253.     s1b = mid(p1, 5, 4);        // s1b = "is a"
  1254.     s1c = right(p1, 4);        // s1c = "test"
  1255.  
  1256. See Also: Left, mid, Mid, right, Right, substr, SubStr
  1257.  
  1258. ---------------------------------------------------------------------------
  1259.  
  1260. justify
  1261. -------
  1262.  
  1263. Syntax:    String justify(char* p, int type, int len,
  1264.                        int mode = String::CLIP|String::TRIM);
  1265.  
  1266. Creates a new string from p and justifies it by padding it with spaces  un-
  1267. til  it  is  'len' long.  The justification  'type'  can  be  String::LEFT,
  1268. String::CENTER, or String::RIGHT.  If p had any leading or trailing  white-
  1269. spaces  (spaces|tabs) then they are first removed if  'mode'|=String::TRIM.
  1270. If the new string is longer than 'len' (after the optional removal of white
  1271. spaces)  then it is clipped to len if 'mode'|=String::CLIP,  otherwise  the
  1272. trimmed string is returned. p remains unmodified.
  1273.  
  1274. Example:
  1275.  
  1276.     char* p1 = "Hello World";
  1277.     String s1a, s1b, s1c;
  1278.  
  1279.     s1a = justify(p1, String::LEFT, 20);
  1280.     s1b = justify(p1, String::CENTER, 20);
  1281.     s1c = justify(p1, String::RIGHT, 20);
  1282.                     // s1a = "Hello World         "
  1283.                     // s1b = "    Hello World     "
  1284.                     // s1c = "         Hello World"
  1285.  
  1286. See Also: Justify, trim, Trim
  1287.  
  1288. ---------------------------------------------------------------------------
  1289.  
  1290. mid
  1291. ---
  1292.  
  1293. Syntax: String mid(char* p, int pos, int len);
  1294.  
  1295. Creates a new string that is the substring of p beginning at position 'pos'
  1296. with length 'len'. p remains unmodified.
  1297.  
  1298. Example:
  1299.  
  1300.     char* p1 = "This is a test";
  1301.     String s1a, s1b, s1c;
  1302.  
  1303.     s1a = left(p1, 4);        // s1a = "This"
  1304.     s1b = mid(p1, 5, 4);        // s1b = "is a"
  1305.     s1c = right(p1, 4);        // s1c = "test"
  1306.  
  1307. See Also: left, Left, Mid, right, Right, substr, SubStr
  1308.  
  1309. ---------------------------------------------------------------------------
  1310.  
  1311. right
  1312. -----
  1313.  
  1314. Syntax: String right(char* p, int len);
  1315.  
  1316. Creates  a  new  string that is the rightmost substring of  p  with  length
  1317. 'len'. p remains unmodified.
  1318.  
  1319. Example:
  1320.  
  1321.     char* p1 = "This is a test";
  1322.     String s1a, s1b, s1c;
  1323.  
  1324.     s1a = left(p1, 4);        // s1a = "This"
  1325.     s1b = mid(p1, 5, 4);        // s1b = "is a"
  1326.     s1c = right(p1, 4);        // s1c = "test"
  1327.  
  1328. See Also: left, Left, mid, Mid, Right, substr, SubStr
  1329.  
  1330. ---------------------------------------------------------------------------
  1331.  
  1332. tolower
  1333. -------
  1334.  
  1335. Syntax: String tolower(String& s);
  1336.  
  1337. Creates a lowercase version of String s. String s remains unmodified.
  1338.  
  1339. Example:
  1340.  
  1341.     String s1 = "LOWERCASE";
  1342.     String s1a;
  1343.  
  1344.     s1a = tolower(s1);        // s1a = "lowercase"
  1345.  
  1346. See Also: SetToLower, SetToUpper, toLower, toupper, toUpper
  1347.  
  1348. ---------------------------------------------------------------------------
  1349.  
  1350. toupper
  1351. -------
  1352.  
  1353. Syntax: String toupper(String& s);
  1354.  
  1355. Creates an uppercase version of String s. String s remains unmodified.
  1356.  
  1357. Example:
  1358.  
  1359.     String s1 = "uppercase";
  1360.     String s1a;
  1361.  
  1362.     s1a = toupper(s1);        // s1a = "UPPERCASE"
  1363.  
  1364. See Also: SetToLower, SetToUpper, tolower, toLower, toUpper
  1365.  
  1366. ---------------------------------------------------------------------------
  1367.  
  1368. trim
  1369. ----
  1370.  
  1371. Syntax: String trim(char* p, int mode = String::CENTER,
  1372.                              char ch = String::WHITESPACE);
  1373.  
  1374. Creates  a new string from p with leading and/or trailing characters  trim-
  1375. med.  The trimmed character 'ch' defaults to  String::WHITESPACE  (spaces &
  1376. tabs) and can be user-defined.  The trim 'mode' defaults to  String::CENTER
  1377. and can also be String::RIGHT or String::LEFT. p remains unmodified.
  1378.  
  1379. Example:
  1380.  
  1381.     char* p1 = "    Spaces    ";
  1382.     String s1a, s1b, s1c;
  1383.  
  1384.     s1a = trim(p1, String::LEFT);    // s1a = "Spaces    "
  1385.     s1b = trim(p1, String::RIGHT);    // s1b = "    Spaces"
  1386.     s1c = trim(p1);            // s1c = "Spaces"
  1387.  
  1388. See Also: Delete, justify, Justify, Trim
  1389.  
  1390. ---------------------------------------------------------------------------
  1391.